<HTML>
<HEAD>
  <STYLE type="text/css">
    H1 {color: black }
    H2 {color: maroon }
    H3 {color: #007090 }
    A.head:link {color: #0060a0 }
    A.head:visited {color: #3040c0 }
    A.head:active {color: white }
    A.head:hover {color: yellow }
    A.red:link {color: red }
    A.red:visited {color: maroon }
    A.red:active {color: yellow }
  </STYLE>
</HEAD>
<TITLE>Magic-8.3 Command Reference</TITLE>
<BODY BACKGROUND=graphics/blpaper.gif>
<H1> <IMG SRC=graphics/magic_title8_3.png ALT="Magic VLSI Layout Tool Version 8.3">
     <IMG SRC=graphics/magic_OGL_sm.gif ALIGN="top" ALT="*"> </H1>

<H2>instance</H2>
<HR>
Operations on cell instances (uses).
<HR>

<H3>Usage:</H3>
   <BLOCKQUOTE>
      <B>instance</B> <I>option</I> <BR><BR>
      <BLOCKQUOTE>
         where <I>option</I> is one of the following:
	 <DL>
	   <DT> [<B>list</B>] <B>children</B> [<I>name</I>]
	   <DD> List all of the children instances of cell use <I>name</I>,
		or the children of the currently selected cell instance.
	   <DT> [<B>list</B>] <B>parent</B> [<I>name</I>]
	   <DD> List the parent cell definition of cell use <I>name</I>,
		or the parent of the currently selected cell instance.
	   <DT> [<B>list</B>] <B>exists</B>|<B>self</B> [<I>name</I>]
	   <DD> Returns the name of the instance if the cell exists, or false
		(0) if the instance does not exist (is not loaded into the
		database; the cell may still exist on disk).  If <I>name</I>
		is not present, returns the name of the currently selected
		instance.
	   <DT> [<B>list</B>] <B>allcells</B>
	   <DD> List all of the cell instances in the database.  Note that
		expansion is not automatic, so cells that are not expanded
		are not searched.
	   <DT> <B>orientation</B> [<I>name</I>] [<B>-def</B>]
	   <DD> Returns the orientation of the instance.  By default, returns
		the orientation in the naming convention used by the
		"<B>getcell</B>" command.  If the option "<B>-def</B>" is
		specified, then the orientation is given in the naming
		convention used by the DEF format for component placement.
		if <I>name</I> is given, then return the orientation of the
		named instance.  Otherwise, the orientation of all selected
		instances is returned as an unordered list.
	   <DT> [<B>list</B>] <B>abutment</B>
	   <DD> Returns the coordinates of the instance's abutment box
		(the bounding box formed by the coordinates saved in the
		FIXED_BBOX property in the cell), translated into the
		coordinate system of the parent cell (which must be the
		edit cell).  This should be used, for example, when
		replacing an instance of a standard cell with another
		standard cell, to move the cursor box to the abutment box
		position so that the new cell has the same alignment as
		the old cell (see also <B>orientation</B>, above).
	   <DT> <B>lock</B>|<B>unlock</B> [<I>name</I>]
	   <DD> Locking an instance prevents it from being moved, rotated,
		flipped, deleted, or copied.  This is useful, for example,
		when part of a layout is declared "final" and changes to
		that area are prohibited.  The cell instance's lock status
		can be saved to and read from the layout file, so the lock
		will remain in effect until the instance is unlocked.
		Cells that are locked have the character "<B>*</B>" prepended
		to the instance name in the display.  With no <I>name</I>
		given to the command, the lock will be applied to all
		selected cell instances.
	 </DL>
      </BLOCKQUOTE>
   </BLOCKQUOTE>

<H3>Summary:</H3>
   <BLOCKQUOTE>
      The <B>instance</B> command performs various operations on
      cell uses, or instances.  For the first four options listed
      above, <B>instance</B> lists cells by their relationship to
      cell use <I>name</I>, or to the current selection if no
      <I>name</I> is given.  The optional argument <B>list</B>
      returns the result as a list.  In particular, in the Tcl
      version of magic, this list is a Tcl result that may be
      operated on by Tcl procedures. <P>
   </BLOCKQUOTE>

<H3>Implementation Notes:</H3>
   <BLOCKQUOTE>
      <B>instance</B> is implemented as a built-in function in <B>magic</B>
      The Tcl version of magic returns Tcl results when the "<B>list</B>"
      option is present.  <B>instance</B> is essentially an alias for the
      <B>cellname</B> command, and takes many of the same options, but
      references are to cell instances rather that cell definitions
      (q.v.).  A number of options to <B>cellname</B> are meaningless
      for instances. <P>

      <I>Warning:</I> Because instance names are arbitrary, looking up
      an instance name is computationally intensive compared to looking
      up a cell name.  When used inside a loop, such as to search the
      cell name hierarchy, use command <B>cellname</B> on cell definitions
      instead of command <B>instance</B> on cell instance names whenever
      possible. <P>

      The command option <B>instance list exists</B> is nonsensical from
      the standpoint of the end-user (if the cell is selected, of course
      it exists).  However, it is a very useful function for Tcl scripts
      to determine the name of the cell instance that is currently
      selected.
   </BLOCKQUOTE>

<H3>Bugs:</H3>
   <BLOCKQUOTE>
      Technically, <B>instance rename</B> should be implemented as a
      replacement for the command <B>identify</B>.
   </BLOCKQUOTE>

<H3>See Also:</H3>
   <BLOCKQUOTE>
      <A HREF=cellname.html><B>cellname</B></A> <BR>
      <A HREF=load.html><B>load</B></A> <BR>
      <A HREF=getcell.html><B>getcell</B></A> <BR>
      <A HREF=tk_path_name.html><I>tk_path_name</I></A> <BR>
   </BLOCKQUOTE>

<P><IMG SRC=graphics/line1.gif><P>
<TABLE BORDER=0>
  <TR>
    <TD> <A HREF=commands.html>Return to command index</A>
  </TR>
</TABLE>
<P><I>Last updated:</I> January 15, 2021 at 12:47pm <P>
</BODY>
</HTML>
